Standard File Operations 
External Reference Specification 
Steven Glass 
August 12, 1986 


First Release May 8,1986 

Hope and Fantasy (never made public) 

Release 2 July 23,1986 

Hope, Fantasy and a little reality thrown in to fool the marks. This was written 
after the first bits and pieces of code were running (still not public) 

Release 3 August 12,1986 

Reality begins to dominate. This is written as the code is about to be released to 
developers for the first time. (This one is public.) 


Standard Hie Operations 

Hie Standard Hie Operations Tool Set provides the standard user interface for specifying 
file to be opened or saved It allows the file to be on a disk in any drive and it allows the 
user to change disks in a drive. 


Data Structures 

Reply Record 


good boolean 

file type word 

anx file type word 

filename string[15] 

full path name string[128] 


True if open pressed; False for cancel. 
ProDOS file type. 

ProDOS aux file type. 

Name of the file in prefix 0. 

Hie full pathname of selected file. 
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Housekeeping Calls 

SFBootMt Internal routine called at load time to initialize the Standard 

File. 

No Stack Parameters 

SFStartup Call made by an application before it makes any other 

Standard File calls. 

Stack Before Call 

I previous contents I 

I ID for Mem Mgr I WORD 

I Address cfZP to Use I WORD 

I k-SP 

Stack After Call 

I previous contents I 

I k-SP 

Standard Hie must be initialized before it is called. The initalization routine allows it to 
have and use a zero page and an ID for any memory that is needed during the standard file 
calk An application may choose to call initialize standard file only when it is needed freeing 
memory for other uses. A typical sequence of code may be 

SFStartup 

SFGetFile (...); 

SFShutdown (...); 

SFShutdown Call made by an application to shutdown after SFStartup is 

called. 

No Stack Parameters 
See SFStartup for more de tails . 

SFVersion Returns the version number of Standard File. 

Stack Before Call 

I previous contents I 

I space for verson I 

I k-SP 

Stack After Call 

I previous contents I 

I version number I 

1 k-SP 


SFReset Resets Standard File. 

No Stack Parameters - 

This is called when the system reset (CONTROL-RESET is pressed). 
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SFActive 


Returns whether or not Standard File is active. 


Stack Before Call 

I previous contents I 

I space for boolean I 

I k-SP 

Stack After Call 

I previous contents I 

I boolean result I 

I k-SP 


Returns true if SFStartup has been called and SFShutdown has not been called. Returns 
false if SFStartup has not been called at all or SFShutdown was called since the last 
SFStartup. 
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Useful Calls 

SFGetFile This is the call that returns a path name for a file selected by 

the user. 

Stack Before Call 


1 previous contents 

1 

1 WhmX 

1 integer 

1 WhereY 

1 integer 

1 PromptPtr 

1 POINTER 

1 FilterProcPtr 

1 POINTER 

1 TypeUstPtr 

1 POINTER 

1 ReplyPtr 

1 POINTER 

1 

k-SP 

Stack After Call 

1 previous contents 

1 

1 

k-SP 


WhereX and WhereY describe the location on the screen (in screen coordinates) of 
the dialog box. 

The PromptPtr points to a string to display at the top of the didog box. This is a 
standard ProDOS string. 

The FilterProcPtr points to a procedure which will decide whether or not a 
particular file will be displayed. Set this pointer to 0 to prevent this procedure from 
being called. The filter proc is called in full native mode as one would call a Pascal 
Function having one long parameter. 

The calling sequence inside SFGetFile is as follows: 

PushWord #0 ; space for result 

PushLong #DirEntry ; pointer to directory entry (27 bytes long) 

jsl FilterProe 

PopWotd Result 

The FilterProe must strip the four bytes off the stack and return with the result at the 
top of stack. 

The filter proc returns with the a result on the stack as follows depending on what it 
wants to do with the file: 

0 if the file is not to be included 

1 if the file is to be included but not selectable 

2 if the file is to be included and is selectable 

The typelist pointer points to a record containing a list of file types to display. The 
list has the following form: 


NumEntries 

byte 

filetypel 

byte 

filetype2 

byte 
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Set the pointer to 0 to display all file types. 

The reply pointer points to a reply record described above. 

When the dialog is displayed, the files from prefix 0, are shown. When the file is selected, 
the name of die file is returned in the reply record and prefix 0 is set the directory 
containing the selected file. If the user cancels the operation, prefix 0 is restored to its 
original state. 

Hie Disk button works differently from the Drive button in the Macintosh. When a user 
pushes Next Disk, Standard File first looks at the disk in the same drive the "current" disk 
is in. If the "current" disk is no longer in that drive, the disk in that drive becomes the 
current disk. If the "current" disk is still there, Next Disk moves to die next disk in the 
ProDOS chain. Next Disk works this way because a user can change disks without the 
system blowing about it 


SFPutFile This is the call that returns a pathname for a file being saved 

as typed by the user. 


Stack Before Call 
I 


previous contents 

1 

WhereX 

1 integer 

WhereY 

1 integer 

PromptPtr 

1 POINTER 

OrigNamePtr 

1 POINTER 

MaxLen 

1 integer 

ReplyPtr 

1 POINTER 
k-SP 

After Call 

previous contents 

1 

k-SP 


WhereX and WhereY describe the location on the screen (in screen coordinates) of 
the dialog box. 

The PromptPtr points to a string to display at the top of the dialog box. This is a 
standard ProDOS string. 

The OrigNamePtr points to a string that holds the original name that appears as the 
default when the dialog first appears. 

The MaxLen parameter specifies the maximum number of characters a user may 
type. Most applications will use 15 for this value but if the application wants to add 
a suffix to the file name, it will shorten this value. 

Hie reply pointer points to a reply record described above. 

There is no filter proc in SFPutFile since the user needs to know all names on the disk to 
avoid any namin g conflicts. 


Standard File Operations 


August 12,1986 


Page 6 




When the dialog is displayed, the files from prefix 0 are shown. When the file is selected, 
the name of die file is returned in the reply record and prefix 0 is set the directory 
containing the selected file. If the user cancels the operation, prefix 0 is restored to its 
original state. 

The Next Disk button works differently from the Drive button in the Macintosh. When a 
user pushes Next Disk, Standard Hie first looks at the disk in the same drive the "current" 
disk is in. If the "current" disk is no longer in that drive, the disk in that drive becomes the 
current disk. If die "current" disk is still there. Next Disk moves to the next disk in the 
ProDOS chain. Next Disk works this way because a user can change disks without the 
system knowing about it 


SFPGetFile This is the call that returns a path name for a file selected by 

the user using a customized dialog box. 

Stack Before Call 


1 previous contents 

1 

1 WhereX 

1 integer 

1 WhereY 

1 integer 

1 PromptPtr 

1 POINTER 

1 FikerProcPtr 

1 POINTER 

1 TypeUstPtr 

1 POINTER 

1 DialogPtr 

1 POINTER 

1 DialogHookPar 

1 POINTER 

1 ReplyPtr 

1 POINTER 

1 

k-SP 

Stack After Call 

1 previous contents 

1 

1 

k-SP 


All but two inputs are identical to die inputs to SFGetHle. 

DialogPtr points to a dialog template in memory. A dialog template is a record 
passed to the dialog manager call GetNewModalDialog. It contains information 
about the dialog to be created including a bounds rectangle and a list of pointers to 
item templates. (See the dialog manager ERS for details.) 

It is important that the template include the following items in this order; 


Item 

Type 

ID 

Open Button 

Button 

1 

Close Button 

Button 

2 

NextButton 

Button 

3 

CancelButton 

Button 

4 

ScrollBar 

Scroll Bar 

5 

Path 

Userltem 

6 

Files 

Userltem 

7 

Prompt 

Userltem 

8 
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The template for the dialog used in SFGetFile is given in the appendix. The 
bounding rectangle for the Files user item determines how many files may be 
displayed. You should set the height of this rectangle to 2 plus 10 times the number 
of files to show. A height of 122 would allow 12 files to be seen. 

DialogHookPtr is a pointer to the routine called by SFPGetFile every time 
ModaJDialog returns a item hit Hie routine is passed a pointer to the dialog port 
and a pointer to the item hit word. If the DialogHook routine wants to handle the 
item hit, it should handle it and set the hit to 0. If the DialogHook routine wants 
SFPGetFile to handle the item hit, it should leave it unchanged. 

Hie routine is called as follows: 

PushLong #DialogPort 
PushLong #ItemHit 
jsl DialogHook 
IdaltemHit 

Your routine must be certain to strip 8 bytes off the stack before returning to 
SFPGetFile. 


SFPPutFile This is the call that returns a pathname for a file being saved 

as typed by the user using a customized dialog box. 

Stack Before Call 

I previous contents 
I WhereX 

I WhereY 

I PromptPtr 

I OrigNamePtr 

I MaxLen 

I DialogPtr 

1 DialogHookPtr 
I RepfyPtr 

I 

Stack After Call 

I previous contents I 

I k-SP 


I 

I integer 
I integer 
I POINTER 
I POINTER 
I integer 
I POINTER 
I POINTER 
I POINTER 
k-SP 


All but two inputs are identical to SFPutFile. The bounding rectangle for the Files 
user item determines how many files may be displayed You should set the height 
of this rectangle to 2 plus 10 times the number of files to show. A height of 122 
would allow 12 files to be seen. 

DialogPtr points to a dialog template in memory. A dialog template is a record 
passed to die dialog manager call GetNewModalDialog. It contains information 
about the dialog to be created including a bounds rectangle and a list of pointers to 
item templates. (See the dialog manager ERS for details.) 

It is important that the template include the following items in this order: 


Standard File Operations 


August 12, 1986 


Page 8 




Item 

Type 

ID 

Save Button 

Button 

1 

Open Button 

Button 

2 

Close Button 

Button 

3 

Next Button 

Button 

4 

Cancel Button 

Button 

5 

ScrollB ar 

Scroll Bar 

6 

Path 

Userltem 

7 

Files 

Userltem 

8 

Prompt 

Userltem 

9 

HleName 

Editltem 

10 

FreeSpace 

Userltem 

11 

Create Button 

Button 

12 


The template for the dialog used in SFPutRle is given in the appendix. 

DialogHookPtr is a pointer to the routine called by SFPPutFile every time 
ModalDialog returns a item hit The routine is passed a pointer to the dialog port 
and a pointer to the item hit word. If the DialogHook routine wants to handle the 
item hit, it should handle it and set the hit to 0. If the DialogHook routine wants 
SFPPutFile to handle the item hit, it should leave it unchanged. 

The routine is called as follows: 

PushLong #DialogPort 
PushLong #ItemHit 
jsl DialogHook 
IdaltemHit 

Your routine must be certain to strip 8 bytes off the stack before returning to 
SFPGetFile. 
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